This document provides information about built-in library functions available in DIRC. It is provided in electronic form due to the dynamic and changing nature of the library functions. The newest version of this document is available via the internet:
FTP://ftp.intrec.com/pub/intrec/mac_files/
HTTP://www.intrec.com
□*** Predefined Constants ***
Some special values have been predefined and given symbolic names to make them easier to use. For example, if you are writing an expression that requires a boolean TRUE value, you could enter the literal number ﾒ1ﾓ (since TRUE is an integer value of 1). As an alternative, you could enter ﾒ#TRUEﾓ. The ﾒ#TRUEﾓ is called a ﾒsymbolic constantﾓ because it is a symbol that represents a constant value. The following predefined constants are available for use within your macro programs:
#TRUE Same as an integer value of 1.
#FALSE Same as an integer value of 0.
#DefnAccess Used by RESIDENT() to control access to resident macros.
#KeyAccess Used by RESIDENT() to control access to resident macros.
#LibAccess Used by RESIDENT() to control access to resident macros.
#EventAccess Used by RESIDENT() to control access to resident macros.
□*** Predefined Functions ***
Most macro programs are actually references to one or more ﾒpredefined functionsﾓ that are included to speed development of macro programs. These functions allow interacting with services, numeric computation and string manipulation, creation and changes to windows and access to the user interface. The functions are listed according to category. A complete alphabetical list and short summary of the functions can be found at the end of the chapter. Throughout this section, the following abbreviations and formatting notations are used:
FUNCTION
The name of the function is displayed in a bold typeface.
INT xxx
An expression that evaluates to an integer must be used in place of this text. The xxx is used within the description of the function to explain the relation of this expression to the operation of the function.
STR xxx
An expression that evaluates to a string must be used in place of this text. The xxx is used within the description of the function to explain the relation of this expression to the operation of the function.
EXPR xxx
Any valid expression (that returns either integer, boolean or string) must be used in place of this text. The xxx is used within the description of the function to explain the relation of this expression to the operation of the function.
[ text ]
Text within brackets represents optional function arguments, not required by the function. The text in brackets will be in one of the preceding formats.
[ ... ]
Three periods within brackets indicates that there can be additional expressions of the preceding type.
□*** Service Interaction Functions ***
The following group of functions are used to interact with a service. The WT()/PR()/SY() functions are the basis for most logon macros. The AutoLearn generator uses these functions when it create logon macros. For those developing complex service interaction macros, it is benefitial to understand the difference between synchronous and asynchronous terminal window operation. For those just getting started with DIRC, skip down to the function descriptions.
** Synchronous & Asynchronous Mode **
By default, the terminal window operates in asyncronous mode. This means that incoming text from the service is displayed as soon as it received. However, when a macro is waiting for some particular text from a service, the terminal window needs to operate in synchronous mode. This means that incoming data is only processed when the macro is ready for it. In most cases, the switch between these modes is made automatically, and the DIRC programmer need not worry about it.
The most common situation which causes confusion is when developing a macro which initially performs some service interaction, and then continues running, but no longer interacts with the service. In this case, the terminal window appears to get ﾒstuckﾓ after the interaction is complete. In fact, the terminal window is actually in synchronous mode and is saving the incoming data waiting for the next WT() function in the macro (which never comes). The terminal window can be forced into asynchronous mode by using the WT(0) function. Likewise, it can be forced into synchronous by using PR("").
** PR() **
PR([INT pace,] STR text);
The PR() function sends the expression text to a service. An optional pace expressions controls the rate at which text is sent in 1/100th of a second (this is the time interval between sending individual characters).
Examples:
PR(ﾒhelloﾓ); // send ﾒhelloﾓ to the service
PR(10,ﾒ@D^mﾓ); // pace=10/100 sec
PR(ﾒﾓ); // force synchronous mode
** PF() **
PF([INT pace,] STR text);
The PF() function is identical to the PR() function except that the PF() function does not display text in the terminal window even if the connect options are set for half duplex. The PF() function is used to conceal passwords and account numbers being sent to half duplex services.
Examples:
PF(ﾒaccountﾓ); // send account information
PF(ﾒpasswordﾓ); // send password information
** SY() **
SY([INT delay,] STR text);
The SY() function attempts to synchronize to a service which requires some character sequence to be sent at intervals. The text (character sequence) is sent at a specified interval expressed in 1/100th of a second (the default is two seconds). If no response is received from the service within the delay period, the process is repeated. This is commonly used at the beginning of logon macros.
Examples:
SY("^m"); // send ^M every 2 secs until response
SY(100,"@D^m"); // send @D^m every 1 sec until response
** WT() **
INT match = WT([INT timeout] [STR text] [ ... ]);
The WT() function waits for a period of time, or until a particular string is received from a service, or for both. The syntax of the WT() function is unusual because all the arguments are optional (though at least one argument is always required). The WT() function is normally used in one of the following forms:
WT(INT timeout);
INT match = WT(STR text, [ ... ]);
INT match = WT(INT timeout, STR text, [ ... ]);
In the first form, WT() waits for a specified period of time (in 1/100ths of a second). In the second form, WT() waits for a string from a service (from a list of one or more strings). In the third form, WT() waits for a string from a service or a period of time, whichever comes first. The result of the WT() function is always 0 for a timeout (the period of time expired) or a number corresponding to the string that was received. If you use WT(ﾒaﾓ,ﾒbﾓ,ﾒcﾓ), then the result is 1 for ﾒaﾓ, 2 for ﾒbﾓ and 3 for ﾒcﾓ. If an empty (null) string is included, any incoming data matches the string. The empty string is normally used with a timeout to detect the absence of incoming data.
Examples:
WT(500); // wait for 5 seconds
WT(ﾒaccount:ﾓ); // wait for the string ﾒaccount:ﾓ
WT(200,ﾒpassword:ﾓ); // wait for 2 secs or ﾒpassword:ﾓ
WT(100,ﾒﾓ); // wait for 1 sec or incoming data
x = WT(100,ﾒmailﾓ); // timeout: x=0; receive ﾒmailﾓ: x=1
DO { WT(ﾒprompt:ﾓ) } WHILE(WT(100,ﾓﾓ)); // wait for prompt or 1 sec inactivity
WT(0); // force asynchronous mode
** IN() **
STR data = IN([INT timeout,]STR terminator[,INT limit][,STR options]);
The IN() function waits for input from a service. The input can be terminated by either a specific termination character (such as RETURN), or a timeout, or an input length limit. The terminator argument is always required, but can be passed as a null string to indicate no terminator should be used. In such a case, the timeout or limit should be used. The timeout is specified in 1/100ths of a second. The limit can range from 1 to 1000 characters. Input is not processed in any way before it is returned (i.e., high-bits are NOT stripped, control characters are NOT removed). If a terminator character is specified and received, it is included as the last character of the input.
Examples:
xyz = IN("^m"); // wait a input terminated by RETURN
ch = IN("",1); // wait for a single character
inp = IN(500,"^m",80); // wait for 5 seconds, a RETURN or 80 characters
** SES_GET() **
STR value = SES_GET([INT session,] STR option);
The SES_GET() function returns the value of a session option. The session indicates which online session the option refers to (when zero or omitted, the current session is used). The option is a string which corresponds to one of the items in a connect file. The following options are supported:
NAME, FILE, PHONE NUMBER, METHOD, SPEED, FORMAT, TIMEOUT, DUPLEX, ECHO, CLOSE WINDOW AFTER CONNECT, SHOW DISCONNECT WINDOW, SHOW ONLINE STATUS WINDOW, IGNORE DUPLEX IN CHAT MODE, RECORD CONNECT IN LOG, LAST CONNECT, DISPLAY, FOREGROUND, BACKGROUND, USE COLOR, CUSTOMIZE, KEYBOARD, DELETE KEY, BACKSPACE, REMOTE PRINT, ANSWERBACK, TERM WINDOW NAME, LINE LIMIT, DELETE COUNT, FONT SIZE, USE EXISTING TERMINAL WINDOW, WARN WHEN TERMINAL WINDOW FULL, SEND MODE, RECEIVE MODE, PROTOCOL SPEED, EXISTING FILES, ALLOW RESUME, AUTO-RECEIVE, PROMPT, CHAR PACE, LINE PACE, TEXT WIDTH, BLANK LINES, PASTE CHAR PACE, PASTE LINE PACE, LOGON MACRO, MACRO, MAC1, MAC2, MAC3, MAC4, MAC5, MAC6, MAC7, MAC8, MAC9
Examples:
PRINT(SES_GET(ﾒSPEEDﾓ));
PRINT(SES_GET(ﾒNAMEﾓ));
** SES_SET() **
SES_SET([INT session,] STR option, STR value);
The SES_SET() function sets the value of a session option. The session indicates which online session the option refers to (when zero or omitted, the current session is used). The option is a string which corresponds to one of the items in a connect file. The value is a string containing the appropriate value for that option. In the case of checkbox options (items that are enabled or disabled), the value is the literal string ﾒ0ﾓ (disabled) or ﾒ1ﾓ (enabled). The following options are supported:
PHONE NUMBER, METHOD, SPEED, FORMAT, TIMEOUT, DUPLEX, ECHO, CLOSE WINDOW AFTER CONNECT, SHOW DISCONNECT WINDOW, SHOW ONLINE STATUS WINDOW, IGNORE DUPLEX IN CHAT MODE, RECORD CONNECT IN LOG, LAST CONNECT, DISPLAY, FOREGROUND, BACKGROUND, USE COLOR, CUSTOMIZE, KEYBOARD, DELETE KEY, BACKSPACE, REMOTE PRINT, ANSWERBACK, TERM WINDOW NAME, LINE LIMIT, DELETE COUNT, FONT SIZE, USE EXISTING TERMINAL WINDOW, WARN WHEN TERMINAL WINDOW FULL, SEND MODE, RECEIVE MODE, PROTOCOL SPEED, EXISTING FILES, ALLOW RESUME, AUTO-RECEIVE, PROMPT, CHAR PACE, LINE PACE, TEXT WIDTH, BLANK LINES, PASTE CHAR PACE, PASTE LINE PACE, LOGON MACRO, MACRO, MAC1, MAC2, MAC3, MAC4, MAC5, MAC6, MAC7, MAC8, MAC9
Examples:
SES_SET(ﾒSPEEDﾓ, ﾒ9600 BPSﾓ);
SES_SET(ﾒDUPLEXﾓ, ﾒFULLﾓ);
□*** Boolean Functions ***
The boolean functions return information about variables and expressions. The results of the boolean functions are always 0 for FALSE and 1 for TRUE. To negate the result of a boolean function, use the ! (exclamation point) operator.
** IS_VAR() **
INT flag = IS_VAR(identifier)
The IS_VAR() function returns the value 0 if identifier is not declared as a variable. It returns the value 1 if identifier is declared as a variable.
Examples:
IF (IS_VAR(init)) { PRINT(ﾒinit is a variableﾓ); };
x = IS_VAR(xyzzy); // x=1 if xyzzy declared as a variable
** IS_NUM() **
INT flag = IS_NUM(EXPR expression)
The IS_NUM() function returns the value 1 if expression is numeric or 0 otherwise. This function is useful for creating functions that can accept either numeric or string arguments.
Examples:
IF IS_NUM(ARGV(1)) { // see if numeric or string
x = ARGV(1); // if numeric, assign immediately
} ELSE { // otherwise
x = NUM_STR(ARGV(1)) // assign convert string to number
}
** IS_STR() **
INT flag = IS_STR(EXPR expression)
The IS_STR() function returns the value 1 if expression is a string or 0 otherwise. This function is useful for creating functions that can accept either numeric or string arguments.
Examples:
IF IS_STR(ARGV(1)) { // see if numeric or string
x = ARGV(1); // if string, assign immediately
} ELSE { // otherwise
x = STR_NUM(ARGV(1)) // convert to string and assign
}
** IS_FILE() **
INT flag = IS_FILE(EXPR expression)
The IS_FILE() function returns the value 1 if expression is the name of a file or 0 otherwise. This function does not check the type of the file or any other attributes. It simply checks to see if a file of the specified name exists.
Examples:
IF IS_FILE(ﾒHD:ProTERM:my-fileﾓ) { // see if the file exists
UI_OPEN(ﾒHD:ProTERM:my-fileﾓ); // if so, open it
}
** IS_class() **
INT flag = IS_class(EXPR expression)
INT flag = IS_ALNUM(EXPR expression)
INT flag = IS_ALPHA(EXPR expression)
INT flag = IS_CNTRL(EXPR expression)
INT flag = IS_DIGIT(EXPR expression)
INT flag = IS_GRAPH(EXPR expression)
INT flag = IS_LOWER(EXPR expression)
INT flag = IS_PRINT(EXPR expression)
INT flag = IS_PUNCT(EXPR expression)
INT flag = IS_SPACE(EXPR expression)
INT flag = IS_UPPER(EXPR expression)
INT flag = IS_HEXID(EXPR expression)
The IS_class() functions returns the value 1 if expression is the particular type of character or 0 otherwise. If expression is an integer, the integer is converted to its ASCII character equivalent for comparison. If expression is a string, only the first character is compared. These functions return the value 1 in the following cases:
IS_ALNUM() If IS_ALPHA() or IS_DIGIT() is TRUE.
IS_ALPHA() If IS_UPPER() or IS_LOWER() is TRUE.
IS_CNTRL() If char is an ASCII control character.
IS_DIGIT() If char is a digit (0-9).
IS_GRAPH() If char is printable character except SPACE.
IS_LOWER() If char is a lowercase letter (a-z).
IS_PRINT() If char is any printable character.
IS_PUNCT() If char is printable except SPACE, a-z, A-Z or 0-9.
IS_SPACE() If char is SPACE, FF, NL, CR, TAB or VT.
IS_UPPER() If char is an uppercase letter (A-Z).
IS_HEXID() If char is a hexidecimal digit (0-9, A-F, a-f).
Examples:
IF IS_LOWER(ﾒaﾓ) { PRINT(ﾒis lowercaseﾓ); }
IF IS_DIGIT(ﾒ5ﾓ) { PRINT(ﾒis digitﾓ); }
IF IS_PRINT(34) { PRINT(ﾒis printableﾓ); }
□*** Numeric Functions ***
The numeric functions perform calculations on expressions resulting in numeric values. In addition to these functions, keep in mind that numeric values can be directly manipulated with the + (addition), - (subtraction/negation), / (division), * (multiplication) and % (remainder/modulus) operators.
** NUM_STR() **
INT value = NUM_STR(STR text);
The NUM_STR() function converts a number in text form to an integer value. The resulting value is a positive or negative integer depending on the format of the number in text form.
Examples:
PRINT(NUM_STR(ﾒ27ﾓ)); // displays 27
xx = NUM_STR(ﾒhelloﾓ); // xx is set to 0
i = NUM_STR(ﾒ-33ﾓ); // i is set to -33
** NUM_CHAR() **
INT value = NUM_CHAR(STR char);
The NUM_CHAR() function returns the character code of the first character of a string. The resulting character code value is in the range 0 to 255. An empty-string returns a value of -1.
Examples:
PRINT(NUM_CHAR(ﾒAﾓ)); // displays 65
xx = NUM_CHAR(ﾒﾓ); // xx is set to -1
** NUM_BYTE() **
INT value = NUM_BYTE(STR data);
The NUM_BYTE() function returns the byte value of the first character of a string. The resulting character code value is in the range 0 to 255. An empty-string returns a value of 0. The NUM_BYTE() function is very similar to the NUM_CHAR() function, and is provided as a counterpart for NUM_WORD() and NUM_LONG().
Examples:
PRINT(NUM_BYTE(ﾒAﾓ)); // displays 65
xx = NUM_BYTE(ﾒﾓ); // xx is set to 0
** NUM_WORD() **
INT value = NUM_WORD(STR data);
The NUM_WORD() function returns the word value of the first two characters of a string. The resulting character code value is in the range 0 to 65535. An empty-string returns a value of 0.
Examples:
PRINT(NUM_WORD(ﾒ@Aﾓ)); // displays 16449
xx = NUM_WORD(ﾒﾓ); // xx is set to 0
** NUM_LONG() **
INT value = NUM_LONG(STR data);
The NUM_LONG() function returns the long word value of the first four characters of a string. The resulting character code value is in the range -2,147,483,684 to 2,147,483,683. An empty-string returns a value of 0.
Examples:
PRINT(NUM_LONG(ﾒABCDﾓ)); // displays 1094861636
xx = NUM_LONG(ﾒxxﾓ); // xx is set to 0 (too short)
** NUM_MIN() **
INT min_value = NUM_MIN(INT val1 [,INT var2] [ ... ]);
The NUM_MIN() function returns the minimum value of all the arguments.
Examples:
PRINT(NUM_MIN(3,2,9)); // display 2
PRINT(NUM_MIN(7,-5)); // display -5
** NUM_MAX() **
INT max_value = NUM_MAX(INT val1 [,INT var2] [ ... ]);
The NUM_MAX() function returns the maximum value of all the arguments.
Examples:
PRINT(NUM_MAX(3,2,9)); // display 9
PRINT(NUM_MAX(7,-5)); // display 7
** NUM_ABS() **
INT pos_value = NUM_ABS(INT pos_neg_value);
The NUM_ABS() function returns the absolute value of pos_neg_value.
Examples:
PRINT(NUM_ABS(-1)); // display 1
PRINT(NUM_ABS(0)); // display 0
PRINT(NUM_ABS(1)); // display 1
** NUM_LO16() **
INT value16 = NUM_LO16(INT value32);
Some functions return values in a ﾒpacked 32-bit formatﾓ. The NUM_LO16() function converts the results of these functions into normal integer values. The packed number is passed as value32 and returned as value16. The conversion performed is to return the lower 16-bits of value32.
Examples:
size = WIN_SIZE(WIN_ACTIVE(0)); // get window size in packed format
PRINT(NUM_LO16(size)); / display horizontal width of window
PRINT(NUM_HI16(size)); // display vertical length of window
** NUM_HI16() **
INT value16 = NUM_HI16(INT value32);
Some functions return values in a ﾒpacked 32-bit formatﾓ. The NUM_HI16() function converts the results of these functions into normal integer values. The packed number is passed as value32 and returned as value16. The conversion performed is to return the upper 16-bits of value32.
Examples:
size = WIN_SIZE(WIN_ACTIVE(0)); // get window size in packed format
PRINT(NUM_LO16(size)); // display horizontal width of window
PRINT(NUM_HI16(size)); / display vertical length of window
** NUM_RND16() **
INT random = NUM_RND16(INT seed);
The NUM_RND16() function returns a random number in the range 0 to 65535. To reduce the range, use the modulus (%) operator. The ﾒrandomﾓ numbers are returned in a periodic sequence that repeats every 65536 times the NUM_RND16() function is used. The seed controls what the next random value will be. If set to -1, then the NUM_RND16() function keeps track of the ﾒseedﾓ value. To generate a repeatable random sequence (one you can start over), use the previous random value as the seed for the next value.
Examples:
x = NUM_RND16(-1) % 1000; // assign ﾒrandomﾓ number between 0ﾉ999
x = 10; // display 10 numbers
rnd = 756; // set the inital random ﾒseedﾓ
WHILE (x=x-1) { // loop 10 times
rnd = NUM_RND16(rnd); // generate random number from previous
PRINT(rnd % 1000,ﾒ^mﾓ); // display random number
} // displays same 10 ﾒrandomﾓ numbers
□*** String Functions ***
The string functions perform calculations on expressions resulting in string values. In addition to these values, keep in mind that strings can also be directly manipulated through the use of the + (concatenation) operator.
** STR_NUM() **
STR text = STR_NUM(INT value);
The STR_NUM() function returns the string equivilent of an integer expression. If value is negative, then the resulting text includes a minus sign.
Examples:
PRINT(STR_NUM(27)); // display the string 27
x = STR_NUM(y)+ﾒ^mﾓ; // create string from var ﾒyﾓ
** STR_CHAR() **
STR text = STR_CHAR(INT char_code);
The STR_CHAR() function returns a text string composed of a single character with the value char_code. If the char_code is greater than 256, then the value modulus 256 is used.
The STR_BYTE() function returns a text string composed of a single character with the value char_code. If the char_code is greater than 256, then the value modulus 256 is used. STR_BYTE() is usually used with NUM_BYTE() to convert values between integers and strings. The STR_BYTE() function is very similar to the STR_CHAR() function, and is provided as a counterpart for STR_WORD() and STR_LONG().
The STR_WORD() function returns a text string composed of two characters which represent the value char_code. If the char_code is greater than 65535, then the value modulus 65536 is used. STR_WORD() is usually used with NUM_WORD() to convert values between integers and strings.
The STR_LONG() function returns a text string composed of four characters which represent the value char_code. STR_LONG() is usually used with NUM_LONG() to convert values between integers and strings.
The STR_TOHEX() function takes a raw binary string (a string containing any character in the range 0-255) and converts it to a hexidecimal coded string (with characters in the range 0-9, A-F). This is a useful way to take binary string data and convert it to a visible format for storage or diagnostic display. The STR_FROMHEX() function (see below) will convert a hexidecimal string back into binary form.
Examples:
PRINT(STR_TOHEX("abc")); // display "616263"
** STR_FROMHEX() **
STR raw = STR_FROMHEX(STR text)
The STR_FROMHEX() function takes a hexidecimal coded text string (a string containing characters in the range 0-9, A-F) and converts it to a binary string (with characters in the range 0-255). This function is used with the STR_TOHEX() function (see above) to convert binary data into and outof a visible string format.
Examples:
PRINT(STR_FROMHEX("616263")); // display "abc"
** STR_LEN() **
INT length = STR_LEN(STR text)
The STR_LEN() function returns the length (in characters) of the text. The length can be in the range 0 and 32,000. The empty string has a length of 0.
Examples:
len = STR_LEN(ﾒhelloﾓ); // assign 5 to the variable ﾒlenﾓ
PRINT(STR_LEN(ﾒﾓ)); // display 0
** STR_LEFT() **
STR left = STR_LEFT(STR text, INT length);
The STR_LEFT() function returns a left string composed of the left-most characters from the text. The length of the left string is equal to length (or less if text is shorter than length). If length is zero, then an empty string is returned.
Examples:
PRINT(STR_LEFT(ﾒabcdeﾓ,3)); // display ﾒabcﾓ
PRINT(STR_LEFT(ﾒ123ﾓ,15)); // display ﾒ123ﾓ
** STR_RIGHT() **
STR right = STR_RIGHT(STR text, INT length);
The STR_RIGHT() function returns a right string composed of the right-most characters from the text. The length of the right string is equal to length (or less if text is shorter than length). If length is zero, then an empty string is returned.
Examples:
PRINT(STR_RIGHT(ﾒabcdeﾓ,3)); // display ﾒcdeﾓ
PRINT(STR_RIGHT(ﾒ123ﾓ,15)); // display ﾒ123ﾓ
** STR_MID() **
STR mid = STR_MID(STR text, INT offset, INT length);
The STR_MID() function returns a mid string composed of characters from the middle of text. The start of the mid string is determined by the offset relative to the left side of text. An offset of zero returns a mid string starting at the left-most character (the same as using the STR_LEFT() function). The length of mid string is equal to length (or less if text is shorter than length). If length is zero, then an empty string is returned.
Examples:
PRINT(STR_MID(ﾒabcdeﾓ,2,2)); // display ﾒcdﾓ
PRINT(STR_MID(ﾒ123ﾓ,2,15)); // display ﾒ3ﾓ
PRINT(STR_MID(ﾒabcdeﾓ,0,3)); // display ﾒabcﾓ
** STR_UPPER() **
STR upper = STR_UPPER(STR text);
The STR_UPPER() function returns text converted to uppercase.
Examples:
PRINT(STR_UPPER(ﾒAbCdEfﾓ)); // display ﾒABCDEFﾓ
** STR_LOWER() **
STR lower = STR_LOWER(STR text);
The STR_LOWER() function returns text converted to lowercase.
Examples:
PRINT(STR_LOWER(ﾒAbCdEfﾓ)); // display ﾒabcdefﾓ
** STR_REPEAT() **
STR pattern = STR_REPEAT(STR text, INT length);
The STR_REPEAT() function returns a pattern created by concatenating text together until the length is reached. The resulting pattern is always exactly length characters.
Examples:
PRINT(STR_REPEAT(ﾒ<>ﾓ,78); // display a line of <><><><>
PRINT(STR_REPEAT(ﾒ-ﾓ,79); // display a line of ------------
** STR_INDEX() **
INT offset = STR_INDEX(STR match, STR target, [INT offset]);
The STR_INDEX() function searches for one string within another. It returns the offset at which the match string occurs within the target string or -1 if it does not occur. The matching portion of the target string must be identical to the match string (includes matching case). The optional offset argument allows the search to be started at a point beyond the first character. Omitting the offset argument is the same as specifying a value of 0 which starts searching from the first character.
Examples:
PRINT(STR_INDEX("c","abcdef")); // display 2
PRINT(STR_INDEX("gs","hello")); // display -1
PRINT(STR_INDEX("c","abcdef",4)); // display -1
** STR_RINDEX() **
INT offset = STR_RINDEX(STR match, STR target, [INT offset]);
The STR_RINDEX() function is very similar to the STR_INDEX() function except that it searches from right-to-left instead of left-to-right. Other than the seach order, the operation is the same. STR_RINDEX() returns the offset at which the match string occurs within the target string or -1 if it does not occur. The matching portion of the target string must be identical to the match string (includes matching case). The optional offset argument allows the search to be started at an arbitrary point.
The STR_FORMAT() function returns a formatted text string. The control string is used as a template for the final formatted text. In addition to normal text, the control string can contain special ﾒformatting tokensﾓ which are replaced in the final text by additional arguments formatted according to the token. The following format tokens are supported:
* Format Tokens *
%% Replace with a percent sign. No argument corresponds to this formatting code.
%c Replace with a single character. The corresponding argument must be an INT containing the character code (0ﾉ255).
%d Replace with a signed decimal value. The corresponding argument must be an INT containing the value.
%s Replace with a string. The corresponding argument must be an STR containing the string.
%u Replace with an unsigned decimal value. The corresponding argument must be an INT containing the value.
%x Replace with the hexadecimal value. The corresponding argument must be an INT containing the value.
%D Replace with a date. The corresponding argument must be an INT containing the date in elapsed seconds from Jan 1, 1904. A value of zero causes replacement with the current date.
%K Replace with a value in ﾒK-bytes.ﾓ The corresponding argument must be an INT containing the number of bytes.
%M Replace with the elapsed time in milliseconds. The corresponding argument must be an INT containing the number of elapsed ticks. To convert seconds to ticks, multiply by 60.
%P Replace with a four-character ﾒtypeﾓ string. The corresponding argument must be an INT containing a ﾒtypeﾓ in ﾒpacked format.ﾓ
%S Replace with the elapsed time in seconds. The corresponding argument must be an INT containing the number of elapsed ticks. To convert seconds to ticks, multiply by 60.
%T Replace with a time. The corresponding argument must be an INT containing the time in elapsed seconds from midnight of any day (including Jan 1, 1904). A value of zero causes replacement with the current time.
%V Replace with a version number. The corresponding argument must be an INT. The resulting value is displayed as the top 16-bits of the value followed by a period followed by the next 8-bit of the value. If the final 8-bit of the value is non-zero, then a period followed by that value is appended.
Examples:
x = STR_FORMAT(ﾒ%dﾓ,27); // conv 27 to string
y = STR_FORMAT(ﾒ%s %sﾓ,a,b); // concat a & b
PRINT(STR_FORMAT(ﾒtime: %D %T^mﾓ,0,0)); // display current date & time
PRINT(STR_FORMAT(ﾒ%d%% doneﾓ,x)); // display a percent value
** STR_PARSE() **
INT items = STR_PARSE(STR text, STR format, [VAR arg1] [...]);
The STR_PARSE() function parses data from text string, assigning it to variables according to a format string. This function operates similar to the C scanf function, except it includes additional control over what defines a string (i.e., it can be more than just a sequence of characters terminated by white-space ). The items value indicates the number of variables assigned by the function.
The actual parsing is controlled by the format string which contains tokens, similar to the STR_FORMAT() function (see above). The tokens are all prefixed by the % character and indicate the type of parsing to take place. The character following a token is used to deliniate the text for parsing purposes. If a space follows a token, than any white-space character (ASCII characters 9, 10, 11, 12, 13 and 32) deliniates the parsing. When a token appears at the end of the formatting string, it is the same as if a space followed the token. Non-token characters within the format string are used to ﾒskipﾓ past text. The following tokens are supported:
* Scan Tokens *
%c Take a single character and assign it to the corresponding string variable.
%d Take a signed number and assign it to the corresponding string. The number with start with either a + or - to indicate its sign. A number is always deliniated by the first non-digit.
%s Take a sequence of characters (a string) and assign itto the corresponding string variable. The character following this token is used to determine what marks the end of the string. Note that the RETURN character always deliniates a string even if another character is specified. To make RETURN the only deliniator character, follow the token with a ^M.
%u Take an unsigned number and assign it to the corresponding string. The number must start with a digit and is deliniated by the first non-digit.
%*<token> The %*c, %*d, %*s, %*u tokens work identical to those above with the *, except they do not assign their values to variables. Instead, they are used strictly as formatting operators to skip past unneeded data.
%<width>s This is a special version of %s which allows a maximum string width to be specified. The maximum width is specified as a decimal number (i.e., %10s).
DIRC does not currently support arrays as an actual data type. Therefore, the following library functions have been provided to allow manipulation of simple array-like data structures. These routines ﾒpackageﾓ array data into a single large ﾒarrayﾓ string which is passed to routines in the library. The routines are simple enough that they can actually be coded directly in DIRC (though the library versions are faster).
** ARRAY_NUM() **
STR array = ARRAY_NUM(INT size);
The ARRAY_NUM() function creates a new array consisting of size numeric elements. The resulting array is a ﾒpacked stringﾓ which must be passed to other array routines in order to get/set the elements.
Examples:
ar = ARRAY_NUM(10); // create a new array
ar = ARRAY_SET(ar,2,x); // set element 2 to x
** ARRAY_STR() **
STR array = ARRAY_STR(INT size, INT width);
The ARRAY_STR() function creates a new array consisting of size string elements of maximum width. The resulting array is a ﾒpacked stringﾓ which must be passed to other array routines in order to get/set the elements.
Examples:
ar = ARRAY_STR(10,20); // create with elements=10, width=20
ar = ARRAY_SET(ar,3,ﾒhelloﾓ); // set element 2 to ﾒhelloﾓ
** ARRAY_SIZE() **
INT size = ARRAY_SIZE(STR array, INT what);
The ARRAY_SIZE() function returns the number of elements in an array or the maximum width of the elements. If the maximum width of an array is 4, then the array is numeric. Otherwise, if the maximum width is greater than 4, then the array contains strings. To get the number of elements, pass 0 in the what argument. To get the maximum element width, pass 1 in the what argument.
Examples:
ar = ARRAY_STR(10,20); // create with elements=10, width=20
PRINT(ARRAY_SIZE(ar,0)); // display number of elements (10)
PRINT(ARRAY_SIZE(ar,1)); // display maximum element width (20)
** ARRAY_GET() **
VAR element = ARRAY_GET(STR array, INT index);
The ARRAY_GET() function returns the contents of an element from an array. The index argument must be within the valid range for the array (or else an error is generated). The returned element will be either a string or integer depending on the type of the array.
Examples:
ar = ARRAY_STR(10,20); // create with elements=10, width=20
ar = ARRAY_SET(ar,5,ﾒhelloﾓ); // set element 5 to ﾒhelloﾓ
PRINT(ARRAY_GET(ar,5)); // display element 5 (hello)
** ARRAY_SET() **
STR array = ARRAY_SET(STR array, VAR data, INT index);
The ARRAY_SET() function sets the contents of an array element and returns an updated array. The index argument must be within the valid range for the array (or else an error is generated). The type of data must agree with the type of the array (integer or string).
Examples:
ar = ARRAY_STR(10,20); // create with elements=10, width=20
ar = ARRAY_SET(ar,5,ﾒhelloﾓ); // set element 5 to ﾒhelloﾓ
PRINT(ARRAY_GET(ar,5)); // display element 5 (hello)
□*** File Functions ***
The following functions are related to the selection and manipulation of files and filenames. To actually input/output information to/from a file, see Input/Output Functions below. Several of the filename function make use of ﾒpathname indexesﾓ which are a simple way of specifying a preset pathname. The pathname indexes are explained below in advance of the functions which use them.
** Pathname Indexes **
There are sixteen pathname indexes available for use by macro programs. Within the application, these indexes are used primarily to keep track of the default pathname for file selector dialogs. For example, index 1 is used to maintain the default folder used for the Open command. The list below tells which indexes are used by the application. A macro can change a pathname index used by the application to make file selection default to a different folder.
0 = Last used pathname
1 = Open pathname
2 = Exec pathname
3 = Send pathname
4 = Receive pathname
5 = Connect folder pathname
6 = Unused
7 = Reserved for macro programs
8-15 = Unused
Each pathname index has two attributes associated with it. The first is the pathname itself which determines the initial folder used during file selection.. The second is called the springback flag which flag determines whether changing the folder during file selection should update the pathname index. For example, when the standard file selector is used with a index value of 1, it starts out at the folder which index 1 represents. During file selection, the folder may get changed. When file selection is completed, the setting of the springback flag determines whether the new folder is saved as the default for subsequent file selection or not.
** Folder Shortcuts **
ProTERM defines three special ﾒshortcutsﾓ which can be used within pathnames to simplify macro development. When shortcuts are used in a pathname, they represent folders which ProTERM considers significant. The following shortcuts work under both System 7 and System 6. The shortcuts are:
.APPL: The folder containing the ProTERM application program.
.SYST: The folder containing the active system software.
.PREF: The folder containing the ProTERM preference files.
Examples:
IF (IS_FILE(".APPL:Test File")) { ... }
EXTERN(".PREF:My-Macros", main());
** FN_RESOLVE() **
STR name = FN_RESOLVE(STR basename, STR filename);
The FN_RESOLVE() function resolves a filename/pathname based on an existing pathname. The basename string is first completely resolved to a folder. The filename string is then resolved relative to the basename folder. If filename is a full pathname (includes a volume name), then the basename has no effect.
Examples:
path = FN_RESOLVE(path,"::"); // get parent pathname
path = FN_RESOLVE(path,"child"); // get child pathname
** FN_WHAT() **
STR name = FN_WHAT(STR pathname);
The FN_WHAT() function returns just the filename portion of a full pathname.
Examples:
file = FN_WHAT("Q240:Desktop Folder:My File");
PRINT(file); // prints "My File"
** FN_WHERE() **
STR path = FN_WHERE(STR pathname);
The FN_WHERE() function returns just the path portion of a full pathname. The filename is removed from the pathname. Note that the path portion of the pathname must be valid in order for this function to work.
Examples:
path = FN_WHERE("Q240:Desktop Folder:My File");
PRINT(path); // prints "Q240:Desktop Folder:"
** FN_PACK() **
STR packed = FN_PACK(STR fullname);
The FN_PACK() function takes a full pathname/filename and returned it in a special "packed" format. In packed format, the total length will never exceed 48 characters, regardless of the pathname. The packed pathname/filename can be converted back to normal form with the FN_UNPK() function.
The FN_UNPK() function takes a packed pathname/filename and converts it back to unpacked form. In unpacked form, the total length is limited only by the number of folders involved in the path.
The FN_SCAN() function returns the names of files present in a particular folder. You can restrict the scan by creator and one or more filetypes and/or by filenames. Set the creator and/or types and/or match to null to avoid restricting the scan. If the filename match string is used, it must be a complete match using * as a wildcard character (case does not matter). The resulting list is returned as a string in array-string format (same as FN_BATCH).
The FN_OPEN() function lets a user choose a file using the standard file selector. The pathname index determine the default folder to start the file selector at (see Pathname Indexes at the start of this section). Button is the name of the button displayed in the file selector. Filetypes is a string containing one or more filetypes which should be displayed (filetypes not listed are not displayed by the file selector window). Use a filetype of "????" to list all files.
The FN_SAVE() function displays a standard file save dialog and allows the user to enter a new filename. The pathname index determines the default folder to start the file selector at (see Pathname Indexes at the start of this section). Prompt is the text displayed as a prompt above the filename input field. Defname is the default filename initially displayed in the filename input field.
Examples:
file = FN_SAVE(1,"Save File As","Untitled");
IF (file == "") { RETURN }
F_CREATE(file);
** FN_PATH() **
STR path = FN_PATH(INT index, STR button);
The FN_PATH() function displays a standard file folder selection dialog. The pathname index determines the default folder to start the file selector at (see Pathname Indexes at the start of this section). Button is the name of the button displayed in the file selector.
Example:
path = FN_PATH(4,"Select");
IF (path != "") { SET_PATH(4,path) }
** FN_BATCH() **
STR batch = FN_BATCH(INT index, STR button);
The FN_BATCH() function displays a batch file selection dialog (same as used in file transfer) and allows the user to select a list of files. The pathname index determines the default folder to start the file selector at (see Pathname Indexes at the start of this section). Button is the name of the button displayed in the batch file selector. The resulting batch is returned as a string-array of filenames. See the ARRAY_SIZE() and ARRAY_GET() functions for information on extracting the individual filenames from the array.
Examples:
batch = FN_BATCH(3,"Done");
IF (batch == "") { RETURN }
fnum = 1;
fmax = ARRAY_SIZE(batch,1);
WHILE (fnum <= fmax) {
PRINT(FN_UNPK(ARRAY_GET(batch,fnum)),"^m");
fnum = fnum + 1;
}
** FN_GETPATH() **
INT pathname = FN_GETPATH(INT index);
The FN_GETPATH() function returns the current pathname for a particular pathname index. See Pathname Indexes at the start of this section for more information.
Examples:
PRINT(FN_GETPATH(1));
** FN_SETPATH() **
FN_SETPATH(INT index, STR pathname);
The FN_SETPATH() function sets the current pathname for a particular pathname index. See Pathname Indexes at the start of this section for more information.
Examples:
FN_SETPATH(1, ﾒHD80:ProTERM:ﾓ);
FN_SETPATH(1, FN_GETPATH(5));
** FN_GETSPR() **
INT spring = FN_GETSPR(INT index);
The FN_GETSPR() function returns the ﾒspringbackﾓ setting of a particular pathname index. See Pathname Indexes at the start of this section for more information.
Examples:
PRINT(FN_GETSPR(1));
** FN_SETSPR() **
FN_SETSPR(INT index, INT spring);
The FN_SETSPR() function sets the ﾒspringbackﾓ option of the particular pathname index. See Pathname Indexes at the start of this section for more information.
Examples:
FN_SETSPR(1, #true);
FN_SETSPR(2, #false);
** F_EXISTS() **
STR type = F_EXISTS(STR filename);
The F_EXISTS() function returns a string which indicates the file type of the file (if it exists) or null (if it does not). If the file is actually a folder, then it returns the string "fldr".
Examples:
IF (F_EXISTS("q240:stuff:test file") != "") { PRINT(ﾒfile existsﾓ) }
** F_CREATE() **
INT error = F_CREATE(STR filename);
The F_CREATE() function creates a new file of the given name (data fork only). The file creator is the same as the application and the file type is TEXT. To change the creator or type, use the F_GETINFO() and F_SETINFO() functions (see below). This function returns zero for no-error, negative for error.
Examples:
F_CREATE("q240:stuff:test file");
** F_FOLDER() **
INT error = F_FOLDER(STR foldername);
THE F_FOLDER() function creates a new empty folder of the given name. This function returns zero for no-error, negative for error.
Examples:
F_FOLDER("Q240:New Folder");
** F_DELETE() **
INT error = F_DELETE(STR filename);
The F_DELETE() function deletes the named file or folder. The return value is zero for no-error, negative for error.
Examples:
F_DELETE("q240:stuff:test file");
** F_RENAME() **
INT error = F_RENAME(STR old_name, STR new_name);
The F_RENAME() function renames a file from old_name to new_name.. The new_name must be a simple filename, or a pathname in the same folder. The F_RENAME() function will not move files. The return value is zero for no-error, negative for error.
Examples:
F_RENAME("q240:stuff:test file","untested file");
** F_GETINFO() **
INT info = F_GETINFO(STR filename);
The F_GETINFO() function returns information about a file in a special "packed" string format. The return value is a 50 byte packed string of information, or the null string if there is an error. The data within the string has the following meaning:
Offset Meaning Access
------ ------- ------
00 Access NUM_BYTE(STR_MID(info,0))
01 unused n/a
02..05 Type STR_MID(info,2,4)
06..09 Creator STR_MID(info,6,4)
10..11 Finder Flags NUM_WORD(STR_MID(info,10))
12..23 unused n/a
24..27 Logical Data Size NUM_LONG(STR_MID(info,24))
28..31 Physical Data Size NUM_LONG(STR_MID(info,28)
The F_SETINFO() function sets information about a file. The information is passed in a special "packed" string format which corresponds to that returned by the F_GETINFO() function (see above). The return value is zero for no-error, negative for an error.
Examples:
info = F_GETINFO("q240:stuff:test file");
info = STR_LEFT(info,2)+"TEXT"+STR_MID(info,6);
F_SETINFO("q240:stuff:test file",info);
** F_OPEN() **
INT file_ref = F_OPEN(STR filename, STR access);
The F_OPEN() function opens an existing file for later input/output via the input/output (see the next section). The access string is equal to "RO", "RW" or "SH" for read-only, read write or shared file access. The return value is a positive "reference number" if the open succeeds, or a negative error code.
Examples:
INT fd = F_OPEN("q240:stuff:test file");
** F_CLOSE() **
INT error = F_CLOSE(INT file_ref);
The F_CLOSE() function closes an open file given its reference number. The return value is zero for no-error, negative for error.
Examples:
F_CLOSE(fd);
□*** Input/Output Functions ***
The input/output functions are used to transfer data from one device to another. A ﾒdeviceﾓ is a generic reference to a programming object such as a files, window, or session. Since devices are a rather abstract concept, something concrete is needed to represent them in programs. All of the I/O routine make use of ﾒreference numbersﾓ (abbreviated refnums) to indicate the device being used. There are functions which return refnums for use with files, windows and sessions. See the functions F_OPEN(), F_CLOSE(), WIN_FIND(), SES_GET() for more information on getting refnums to devices.
** IO_PRINTF() **
INT error = IO_PRINTF(INT refnum, STR format, [VAR arg1] [ ... ])
The IO_PRINTF() function creates a formatted text string and outputs it to the refnum device. The control string is used as a template for the final formatted text. In addition to normal text, the control string can contain special ﾒformatting codesﾓ which are replaced in the final text by additional arguments formatted according to the code. See the STR_FORMAT() function for syntax of the control string.
Examples:
err = IO_PRINT(fd,ﾒ%d^mﾓ,x);
** IO_SCANF() **
INT items = IO_SCANF(INT refnum, STR format, [VAR arg1] [ ... ]);
The IO_SCANF() function parses data from a device, assigning it to variables according to a format string. This function operates similar to the C scanf function, except it includes some additional control over what defines a string (i.e., it can be more than just a white-space terminated sequence of characters). The return value indicates the number of variables assigned by the function. The syntax of the format string is identical to that used by STR_PARSE().
Examples:
IO_SCANF(fd,"%s^m",text);
** IO_READ() **
STR data = IO_READ(INT refnum, INT length);
The IO_READ() function returns a string of 'length' bytes read from the device. The refnum could be a file_ref from a F_OPEN() function, or a reference to some other device* (such as a window). A null string is returned for any kind of error.
Examples:
text = IO_READ(fd,32);
** IO_WRITE() **
INT count = IO_WRITE(INT refnum, INT length, STR data);
The IO_WRITE() function writes a string of 'length' bytes to a device. If'length' is smaller than the size of string, only 'length' characters are written. Otherwise, if 'length' is larger than the size of the string, the write is "padded" with null characters until 'length' bytes are written. By passing an empty string, you can quickly write a sequence of nulls to a device. The return value is the number of bytes actually written.
Examples:
IO_WRITE(#OutChan,50,"Hello World");
** IO_COPY() **
INT length = IO_COPY(INT inp_ref, INT out_ref, INT limit | STR term_chars );
The IO_COPY() function copyies data from one device to another. The amount of data copied is determined by the thind argument. If this argument is a number, it represents the number of bytes to copy. If this argument is a string, it represents a list of "terminator characters" which mark the end of the copy. The null-string copies the entire contents of the input device to the output device.
The IO_GETLEN() function returns the length of a device. The refnum can be a file_ref from F_OPEN(), a win_ref from WIN_FIND(), or a reference to some other device (such as a session). The result is the length of the device or -1 if the length is unavailable.
Examples:
size = IO_GETLEN(fd);
** IO_SETLEN() **
INT error = IO_SETLEN(INT refnum, INT length);
The IO_SETLEN() function sets the length of a device. The refnum can be a file_ref from a F_OPEN() function, or a reference to some other device (such as a window). The return value is zero for no-error, negative for error.
Examples:
IO_SETLEN(fd,size);
** IO_GETPOS() **
INT position = IO_GETPOS(INT refnum);
The IO_GETPOS() function returns the read/write position of a device. The refnum can be a file_ref from a F_OPEN() function, or a reference to some other device (such as a window). The result is the read/write position of the device or -1 if the position is unavailable.
Examples:
pos = IO_GETPOS(fd);
** IO_SETPOS() **
INT error = IO_SETPOS(INT refnum, INT position);
The IO_SETPOS() function sets the read/write position of a device. The refnum can be a file_ref from a F_OPEN() function, or a reference to some other device (such as a window). The return value is zero for no-error, negative for error.
Examples:
IO_SETPOS(fd,pos)
** IO_GETSEL() **
INT position = IO_GETSEL(INT refnum);
The IO_GETSEL() function returns the ﾒanchorﾓ position of a device. The refnum can be a win_ref from WIN_ACTIVE() (files do not support anchor points). The result is the anchor position of the device or -1 if the anchor position is unavailable.
Examples:
pos = IO_GETSEL(fd);
** IO_SETSEL() **
INT error = IO_SETSEL(INT refnum, INT position);
The IO_SETSEL() function sets the ﾒanchorﾓ position of a device. The refnum can be a win_ref from WIN_ACTIVE() (files do not support anchor points). The return value is zero for no-error, negative for error. Setting the anchor position to point different from the read/write position usually has the effect of creating a selection, though the exact result differs from device to device.
Examples:
IO_SETSEL(fd,pos)
** IO_INPCHAN() **
IO_INPCHAN(INT alias, INT refnum);
The IO_INPCHAN() function allows remapping of input half of a device alias. All subsequent input from the alias will get its input from refnum instead.
Examples:
IO_INPCHAN(#stdin,refnum);
** IO_OUTCHAN() **
IO_OUTCHAN(INT alias, INT refnum);
The IO_OUTCHAN() function allows remapping of output half of a device alias. All subsequent output to the alias will be sent to refnum instead.
Examples:
IO_OUTCHAN(#stdin,refnum);
□*** Miscellaneous Functions ***
The following functions do not fit into any particular category or description.
** PRINT() **
PRINT(EXPR data, [ ... ]);
The PRINT() function displays the value of each argument in the Macro Output window. There can be one or more arguments and each can be either an integer or a string.
Examples:
PRINT(ﾒhello worldﾓ); // display ﾒhello worldﾓ
PRINT(27); // display 27
PRINT(TICKS(),ﾒ^mﾓ); // displays tick count plus return
PRINT(1,ﾒ2ﾓ,3,ﾒ^mﾓ); // display ﾒ123ﾓ plus return
** PRINTF() **
PRINTF(STR control, [EXPR arg1] [ ... ]);
The PRINTF() function creates a formatted text string and displays it in the Macro Output window. The control string is used as a template for the final formatted text. In addition to normal text, the control string can contain special ﾒformatting codesﾓ which are replaced in the final text by additional arguments formatted according to the code. See the STR_FORMAT() function for syntax of the control string.
Examples:
PRINTF(ﾒtime: %D %T^mﾓ, 0,0); // display current date & time
PRINTF(ﾒ%d%% doneﾓ, x); // display a percent value
** TIME() **
INT time = TIME(INT where);
The TIME() function returns the current time in elapsed seconds from January 1, 1904. The where argument indicates if the time should be returned in local (where = 0) or GMT (where = 1). By recording the value of TIME() and then subtracting it from a later value, you can determine elapsed time.
Examples:
start = TIME(); // record the start time
...do something... // perform some computations
et = TIME()-start; // compute elapsed time
PRINT(et); // display elapsed seconds
** TICK() **
INT tick = TICK();
The TICK() function returns the elapsed ﾒticksﾓ since the computer was last restarted. A tick occurs every 1/60 of a second. By recording the value of TICK() and then subtracting it from a later value, you can determine elapsed ticks.
The ARGV() function returns a function argument by its index number. Each argument passed to a function is numbered starting at one and can be retrieved with the ARGV() function. Arguments beyond those specified in the function declaration can only be accessed with the ARGV() function.
Examples:
PRINT(ARGV(1)); // print the first function argument
PRINT(ARGV(2)); // print the second function argument
** ARGC() **
INT count = ARGC();
The ARGC() function returns a count of the arguments passed to the current function. The ARGC() function is used to create functions that can accept a variable number of arguments. If no arguments were passed to the current function, ARGC() returns a count of 0.
Example:
FUNC print2() // declare function without args
{ // start of func compound expr
INT i = 0; // start argument index at 0
WHILE ((i=i+1) <= ARGC()) { // while index < total arguments, loop
PRINT(ARGV(i); // display the argument
}
RETURN; // return from function (void)
} // end of func compound expr
** ERROR(STR error_message); **
The ERROR() function causes a macro error and displays the error_message argument as the error cause. This function is useful in writing library routines which will be called by other macros. It provides a clean way to terminate a macro and provide an explanation to the user.
Examples:
ERROR("Out of Range");
** GESTALT() **
STR result = GESTALT(descriptor);
The GESTALT() function returns attributes of the environment in which the macro is executing. The descriptor (listed below) is the name of the attribute which should be returned. If the descriptor is invalid, GESTALT() returns a null string. The GESTALT() function can be used to see if the particular version of the software is in use or return information about the computer hardware.
The following descriptors are supported:
appl Returns the name of the application (ProTERM).
vers Returns the ProTERM version name.
name Returns the name of the registered user.
org Returns the organization of the registered user.
serial Returns the software serial number.
mac Returns the model name of the Macintosh hardware.
cpu Returns the cpu/fpu being used.
ram Returns the physical memory in the computer.
rom Returns the size of the ROM in the computer.
update Returns the installed update file version (4-digit string)
NOTE: You can actually add your own GESTALT() values by declaring a shared string variable of the desired name. If you create your own macro library, you can use GESTALT() to ﾒadvertiseﾓ when it is available and what version is being used.
NOTE: Experts-- GESTALT() can also be used to query the system software about attributes of the current software/hardware. To call the toolbox _GESTALT function, use the form: INT value = GESTALT(NUM_LONG("selector")); where 'selector' is the 4 byte _GESTALT selector.
Examples:
PR(GESTALT(name)); // send user name to the service
PRINT(GESTALT(mac)); // display Mac hardware model
sysv = GESTALT(NUM_LONG("sysv")); // get system software version
** EXTERN() **
INT result = EXTERN(STR macro_file, EXPR expression);
The EXTERN() function evaluates an expression within the context of a different macro file. All function references in expression are executed from macro_file instead of from the current program. The result returned by EXTERN() is the result of the expression. If macro_file is null, then the expression is evaluated from the disk-based copy of the current macro program (not the copy already in memory).
Examples:
EXTERN(ﾒlibraryﾓ,main()); // exec a different macro file
x = EXTERN(ﾒlibﾓ, sum(1, 2)); // exec the function ﾒsumﾓ in the file ﾒlibﾓ
** RESIDENT() **
RESIDENT(STR macro_file, INT owner, INT access);
The RESIDENT() function is used to make a macro_file resident. If the macro_file is null, then the RESIDENT() function affects the current macro program. The owner is a number between 0 and 32,000 that identifies the macro_file and controls how the macro_file can be accessed. The owner should always be set to 0. The access argument indicates how functions in the macro_file can be executed (keyboard, event, library). An access of -1 means that macro_file should no longer be kept resident.
The values for the access argument are all predefined constants. Each constant allows a certain type of access to the macro file. All of the desired access types should be added together as the access expression.
#KeyAccess
The macro file is scanned for KEY_0000(), KTR_0000() and KED_0000() functions that correspond to otherwise unused keypresses.
#EventAccess
The macro file is scanned for EV_xxxx() functions that correspond to ProTERM events.
#LibAccess
The macro file is scanned when a function reference in a different macro file cannot locate a matching function declaration.
#DefnAccess
The macro file is scanned for KDF_0000() functions that correspond to every keypress. This kind of access allows any possible keypress to activate a macro (even keys that should be performing some other function). Use of this access type is not recommended.
Examples:
RESIDENT(ﾒﾓ, 0, #KeyAccess+#EventAccess);
// make resident and allow keyboard/event access
RESIDENT(ﾒﾓ, 0, -1); // remove resident status
** TIME_OF() **
INT time = TIME_OF(INT year, INT month, INT day, INT hour, INT min, INT sec);
The TIME_OF() function converts a given year, month, day, hour, minute and second into a single time value which represents the number of elapsed seconds from January 1, 1904. This is the same time format used by all the other macro time routines.
Examples:
tm = TIME_OF(1995,3,22,18,56,17); // return value for 3/22/95 6:56:17 pm
** TIME_TO() **
INT value = TIME_TO(INT time, INT select);
The TIME_TO() function returns either the year, month, day, hour, minute, second or day-of-week component from a time value. The select values are 0=year, 1=month, 2=day, 3=hour, 4=minute, 5=second, 6=day-of-week. A time value of 0 is equivilent to the "current time".
Examples:
month = TIME_TO(0,1); // extract current month
year = TIME_TO(0,0); // extract current year
day = TIME_TO(0,2); // extract current day
PRINTF("%02d/%02d/%02d",month,year,day);
□*** User Interface Functions ***
User Interface Functions
The following group of functions allow control over the user interface. These functions allow a macro program to perform operations such as choosing a command from a menu, clicking a button in a window or entering text. For other functions which can control the user interface, see Dialog Interface Functions below.
** UI_NEW() **
UI_NEW(STR file_name);
The UI_NEW() function creates a new editor document with the specified name. It is functually equivilent to choosing the New command followed by the Save command and entering a filename. To create the file in a particular folder, the file name should include the folder path specification.
The UI_OPEN() function opens an existing file. The type of the file determines how it is opened (as an editor, connect or terminal window document). The file name should include the folder path specification for the file.
Examples:
UI_OPEN(ﾒExisting Fileﾓ); // open a document called test file
UI_OPEN(ﾒHD80:ProTERM:Existing Fileﾓ);
** UI_CLOSE() **
UI_CLOSE(STR file_name);
The UI_CLOSE() function closes an open document of the corresponding name. All open documents are scanned until one with a matching name is located. Note that the UI_CLOSE() function does not prompt you to save changes to the document even if it has been changed. If you want to save changes to the document, use the UI_SAVE() function prior to the UI_CLOSE() function.
Examples:
UI_CLOSE(ﾒTest Fileﾓ); // close a document called test file
UI_CLOSE(ﾒHD80:ProTERM:Test Fileﾓ);
** UI_SAVE() **
UI_SAVE(STR file_name);
The UI_SAVE() function saves the changes to an open document of the corresponding name. All open documents are scanned until one with a matching name is located.
Examples:
UI_SAVE(ﾒTest Fileﾓ); // save a document called test file
UI_SAVE(ﾒHD80:ProTERM:Test Fileﾓ);
** UI_CLICK() **
UI_CLICK(STR button_name);
The UI_CLICK() function clicks a button in the active window. The button_name must be completely spelled out, but uppercase and lowercase do not matter.
Examples:
UI_CLICK(ﾒOKﾓ); // click the OK button
UI_CLICK(ﾒmacrosﾓ); // click Macros radio button
** UI_SET() **
UI_SET(STR item_name, STR value);
The UI_SET() function sets the value of an item in the active window. The item_name must be completely spelled out, but uppercase/lowercase and any trailing colon do not matter. The new value of the item must correspond to a valid choice for that item (i.e., if item_name is a pop-up`, then value must be one of the choices in the pop-up menu).
Examples:
UI_SET(ﾒspeedﾓ, ﾒ9600 BPSﾓ); // set the speed option to 9600 bps
UI_SET(ﾒSpeedﾓ, ﾒ2400 BPSﾓ); // set the speed option to 2400 bps
UI_SET(ﾒSPEED:ﾓ, ﾒ300 BPSﾓ); // set the speed option to 300 bps
** UI_GET() **
STR value = UI_GET(STR item_name);
The UI_GET() function returns the current value of an item in the active window. The item_name must be completely spelled out, but uppercase and lowercase, and any trailing colons do not matter.
Examples:
speed = UI_GET(ﾒspeedﾓ); // get the speed option
phone = UI_GET(ﾒDuplex:ﾓ); // get the duplex option
** UI_MENU() **
UI_MENU(STR command_name);
The UI_MENU() function chooses a command_name from one of the pull-down menus. The command_name must be expressed as ﾒmenu:commandﾓ, or if located in a submenu, ﾒmenu:submenu:commandﾓ. The names of the menus and commands must be completely spelled out, but uppercase and lowercase does not matter.
Examples:
UI_MENU(ﾒEdit:Convert:Lower Caseﾓ); // choose lowercase from convert menu
UI_MENU(ﾒfile:openﾓ); // choose file from the open menu
** UI_EQUIV() **
UI_EQUIV(STR command_name, STR key_equiv);
The UI_EQUIV() function sets the keyboard equivalent (shortcut) for a menu command. The command_name must be expressed as ﾒmenu:commandﾓ, or if located in a submenu, ﾒmenu:submenu:commandﾓ. The names of the menus and commands must be completely spelled out, but uppercase/lowercase does not matter. The key_equiv should be a single character. Once a keyboard equivalent is set, it remains in effect until ProTERM quits or the shortcut is changed with another UI_EQUIV() function. To remove the keyboard equivalent from command_name, pass the empty string (ﾒﾓ).
Examples:
UI_EQUIV(ﾒEdit:Convert:Lowercaseﾓ,ﾒLﾓ); // make COMMAND+L into shortcut
UI_EQUIV(ﾒFile:Printﾓ, ﾒﾓ); // remove shortcut from print
** UI_TYPE() **
UI_TYPE(STR text);
The UI_TYPE() function makes it appear that text is being typed at the keyboard. Text is processed by the active window. The UI_TYPE() function is normally used to insert text into an editor window. Text is always inserted at the insertion point.
Examples:
UI_TYPE(ﾒhello worldﾓ); // enter the text ﾒhello worldﾓ
UI_TYPE(ﾔThis is a ﾒQuoteﾓ Testﾕ);
** UI_CLIP() **
STR from_clip = UI_CLIP(STR to_clip);
INT value = UI_CLIP(INT flag);
The UI_CLIP() function allows text to be copied to the clipboard or the current clipboard contents to be read. To read the clipboard, pass the null string as the function argument. The clipboard contents are returned as a single string. To copy text to the clipboard, pass the text to the UI_CLIP function. That text replaces the previous contents of the clipboard. By passing a value of zero to UI_CLIP(), you can determine the size of the data in the clipboard.
Examples:
clip = UI_CLIP(""); // get current clipboard contents
UI_CLIP("hello"); // put "hello" on the clipboard
x = UI_CLIP(0); // assign x the size of clipboard contents
** UI_SOUND() **
UI_SOUND(STR sound);
The UI_SOUND() function allows a macro to play a sound resource. The sound must be an available sound resource. The easiest way to determine a list of available sounds is to look at one of the sound pop-up menus in the Sounds page of the Preferences.
After the UI_SOUND function starts playing a sound, it resumes macro execution immediately BEFORE the sound has finished playing. To wait for completion of the current sound, pass the null string as the sound_name.
Examples:
UI_SOUND("Simple Beep"); // play the standard beep
** UI_SPEAK() **
UI_SPEAK(STR speak_text);
The UI_SPEAK() function allows a macro to use the Speech Manager (if installed) to speak. After the UI_SPEAK() function starts speaking, it resumes macro execution BEFORE the speech has finished. To wait for completion of the speech, pass the null string as the speak_text.
To determine if the Speech Manager is installed (and whether UI_SPEAK can be used), use the GESTALT() function with the SPEECH descriptor. If the result is anything but ﾒNo", you can assume speech is present.
Examples:
IF (GESTALT(SPEECH) != "No") { UI_SPEAK("Hello World"); }
UI_SPEAK(""); // wait for current speech to complete
** UI_CMD **
STR result = UI_CMD(STR cdl);
The UI_CMD() function is not intended for use by the average user. It is an interface to a special internal command language used by the application to control its actions. Certain complex functions use UI_CMD() in order to interface more directly with internal routines.
** UI_NUM **
INT value = UI_NUM(STR parm INT index, STR cdl_result);
The UI_NUM() function is used to extract a numeric result value generated by the UI_CMD() function. It is not intended for use by the average user and is included only for completeness.
** UI_STR **
STR value = UI_STR(STR parm INT index, STR cdl_result);
The UI_STR() function is used to extract a string result value generated by the UI_CMD() function. It is not intended for use by the average user and is included only for completeness.
□*** Window Functions ***
The following group of functions control the manipulation of windows. The WIN_OPEN(), WIN_MACRO(), WIN_BUTTON(), WIN_ICON() and WIN_PICT() allow special windows to be created that execute macros in response to clicking in the window.
** WIN_OPEN() **
INT window_id = WIN_OPEN(STR title, INT type, INT width, INT length);
The WIN_OPEN() function creates a special kind of ﾒmacro windowﾓ to which you can add buttons, icons and pictures. You can then add specific macros which are executed in response to clicking in the window with the mouse. The window type is 0 for a standard window (like an editor window) and 1 for a floating window (like the keypad window). The width and length specify the initial size of the window in pixels. The window_id returned by this function must be saved in a variable for use with the WIN_MACRO(), WIN_BUTTON(), WIN_ICON() and WIN_PICT() functions.
The resulting window has ﾒspacesﾓ reserved to display items. Each space is numbered from 1 to 20 and can be assigned a unique button, icon or picture to identify it. Each space can also be assigned a macro to execute when the corresponding button, icon or picture is clicked with the mouse. Whenever the window is displayed, the items are displayed left to right, top to bottom starting with item 1. Whenever the window is resized, the items are redisplayed in a ﾒbest fitﾓ format.
NOTE: If the length value is negative, this acts as a flag to tell DIRC to maintain the size and position of the window between uses. Whenever the user changes the size of the window, DIRC will remember it for next time.
Examples:
win = WIN_OPEN(ﾒTestﾓ,0,200,200); // open a normal window called ﾒtestﾓ
win = WIN_OPEN(ﾒﾓ,1,200,300); // open an untitled floating window
** WIN_BUTTON() **
WIN_BUTTON(INT window_id, INT item_num, STR button_name);
The WIN_BUTTON() function adds a button to a macro window. The window_id must be from a prior WIN_OPEN() function. The item_num should be in the range 1 to 20 and correspond to the desired ﾒitem spaceﾓ (where 1 is at the upper-left corner and 20 is towards the lower-right). The button_name should be limited to no more than 15 characters total.
The text for button names should always be left-justified. In order to pad the width of a button (add more space between the button name and the frame), add trailing spaces to the button text. To make multiple buttons have the same width, make sure they all have the same number of characters in the button text (including trailing spaces).
Examples:
WIN_BUTTON(win,1,ﾒbtnﾓ); // add button called ﾒbtnﾓ
WIN_BUTTON(win, 1, "Ymodem ");
WIN_BUTTON(win, 2, "Ymodem-4K ");
WIN_BUTTON(win, 3, "Ymodem-G ");
** WIN_ICON() **
WIN_ICON(INT window_id, INT item_space, STR icon_name);
The WIN_ICON() function adds an icon to a macro window. The window_id must be a result from a prior WIN_OPEN() function. The item_num should be in the range 1 to 20 and correspond to the desired ﾒitem spaceﾓ (where 1 is at the upper-left corner and 20 is towards the lower-right). The icon_name is the name of an icon resource. Valid icon_names can be determined by choosing Macro Icon Info from the Tools: Additions submenu.
Examples:
WIN_ICON(win,1,ﾒstopﾓ); // add ﾒstopﾓ icon to win
** WIN_PICT() **
WIN_PICT(INT window_id, INT item_num, STR pict_name);
The WIN_PICT() function adds a picture to a macro window. The window_id must be from a prior WIN_OPEN() function. The item_num should be in the range 1 to 20 and correspond to the desired ﾒitem spaceﾓ (where 1 is at the upper-left corner and 20 is towards the lower-right). The pict_name is the name of a picture resource. Valid pict_names can be determined by choosing Macro Icon Info from the Tools: Additions submenu.
Examples:
WIN_PICT(win, 1, ﾒintrecﾓ); // add intrec pict to win
** WIN_CLICK() **
INT item_space = WIN_CLICK(INT window_id);
The WIN_CLICK() function waits for a click on an item (button, icon or picture) in a macro window. The window_id must be from a prior WIN_OPEN() function. The item_space value represents the corresponding number of the item. An item_space value of -1 means that the macro window was closed.
Examples:
item = WIN_CLICK(WIN_FIND(ﾒMacro Windowﾓ));
** WIN_MACRO() **
WIN_MACRO(INT window_id, INT item_space, STR macro_text);
The WIN_MACRO() function associates a macro with an item (button, icon or picture) in a macro window. The item_space is a number between 1 and 20 that corresponds to the button, icon or picture that should be associated with the macro. The macro_text must be a complete stand-alone macro that could be executed as its own program. It must include all function and variable declarations required for it to execute.
When you click on the corresponding item, the macro_text is executed as a stand-alone macro independent of the macro program which referenced the WIN_MACRO function. If you want to ﾒcommunicateﾓ between the two macros, you must use SESSION or SHARED variables. When the macro_text finishes executing, it does not return any kind of result to WIN_MACRO.
Examples:
win = WIN_OPEN(ﾒTestﾓ,0,100,100);
WIN_MACRO(win,1,ﾔprint(ﾒhello worldﾓ);ﾕ);
WIN_BUTTON(win,1,ﾒ#1ﾓ);
** WIN_FIND() **
INT window_id = WIN_FIND(STR title, [STR type]);
The WIN_FIND() function returns the window_id of an open window. The title must be exactly the same as the title of the window (both uppercase and lowercase count). If a type string is specified, it must correspond to the four-character type of the window. If the title is null, then any window matching the type field will be returned. If WIN_FIND() cannot locate the window, it returns a value of 0.
Examples:
win = WIN_FIND(ﾒTest Windowﾓ); // return window_id of ﾒTest Windowﾓ
WIN_ACTIVE(WIN_FIND(ﾒThe InTrec BBSﾓ)); // make ﾒThe InTrec BBSﾓ window active
** WIN_FILE() **
INT window_id = WIN_FILE(STR file);
The WIN_FILE() function returns the window_id of an open document window. The file must be exactly the same as the name of the file that corresponds to the window. If WIN_FILE() cannot locate the window, it returns a value of 0.
Examples:
win = WIN_FIND(ﾒHD80:PT:Editor Docﾓ); // return id of ﾒEditor Docﾓ window
WIN_ACTIVE(WIN_FIND(ﾒHD80:PT:InTrecﾓ)); // make ﾒInTrecﾓ window active
** WIN_ACTIVE() **
INT window_id = WIN_ACTIVE(INT window_id);
The WIN_ACTIVE() function selects and/or returns the active window_id. If the window_id passed to WIN_ACTIVE() is valid, then that window is made active. The WIN_ACTIVE() function always returns the window_id of the active window or 0 if no window is open. To get the window_id of the active window without changing anything, pass a window_id of 0.
Examples:
win = WIN_ACTIVE(0); // assign active window_id
WIN_ACTIVE(WIN_FIND(ﾒModem Control Monitorﾓ));
// make ﾒmodem controlﾓ window active
** WIN_MOVE() **
INT position = WIN_MOVE(INT window_id, INT horiz, INT vert);
The WIN_MOVE() function moves and/or returns the position of a window. The window to be moved is indicated by the window_id. The new horizontal and vertical position of the window is indicated in pixels (where 0,0 is the upper-left corner of the screen). To get the position of a window without changing it, pass vertical and horizontal both set to 0.
The position returned by the WIN_MOVE() function is in a special format. To convert the position into standard horizontal and vertical components, use the NUM_LO16() and NUM_HI16() functions. The horizontal position is equal to NUM_LO16(position) while the vertical position is equal to NUM_HI16(position).
Examples:
pos = WIN_MOVE(win,0,0); // get position of window
horiz = NUM_LO16(pos); // extract horizontal position
vert = NUM_HI16(pos); // extract vertical position
WIN_MOVE(WIN_ACTIVE(0),50,50);
** WIN_SIZE() **
INT size = WIN_SIZE(INT window_id, INT horiz, INT vertical);
The WIN_SIZE() function resizes and/or returns the size of a window. The window to be resized is indicated by the window_id. The new horizontal and vertical size of the window is indicated in pixels. To return the size of a window without changing it, pass vertical and horizontal both set to 0. You can only resize a window that can normally be resized with the mouse (a window with a grow box).
The size returned by the WIN_SIZE() function is in a special format. To convert the size into standard horizontal and vertical components, use the NUM_LO16() and NUM_HI16() functions. The horizontal size is equal to NUM_LO16(size) while the vertical size is equal to NUM_HI16(size).
Examples:
size = WIN_SIZE(win,0,0); / get the size of the window
WIN_SIZE(WIN_ACTIVE(0),100,200); // set size of the active window
** WIN_ZOOM() **
STR state = WIN_ZOOM(INT window_id, STR zoom);
The WIN_ZOOM() function zooms and/or returns the zoom state of a window. The window to zoom is indicated by the window_id. The zoom string is a single character that indicates the new zoom state. The following states are supported:
~ Toggles between normal and zoom
< Zoom to minimum size
> Zoom to maximum size
{ Zoom to maximum vertical size
} Zoom to maximum horizontal size
- Change to normal state
+ Change to zoom state
The state returned by WIN_ZOOM() indicates the zoom state of the window (and corresponds to the table above). To get the zoom state of the window without changing it, pass an empty zoom string.
Examples:
WIN_ZOOM(WIN_ACTIVE(0)),ﾒ~ﾓ);
zoom = WIN_ZOOM(win, ﾒﾓ);
** WIN_NAME() **
STR name = WIN_NAME(INT window_id);
The WIN_NAME() function returns the name of an open window. The name corresponds to the name displayed in the title bar of the window.
Examples:
PRINTF(ﾒWindow name = %s^mﾓ, WIN_NAME(WIN_ACTIVE(0)));
** WIN_TYPE() **
STR type = WIN_TYPE(INT window_id);
The WIN_TYPE() function returns a special four character type string for the window. The type string can be used to identify one kind of window from another. For example, an editor window returns a different type than a terminal window.
Examples:
PRINTF(ﾒWindow type = %s^mﾓ, WIN_TYPE(WIN_ACTIVE(0)));
IF (WIN_TYPE(win) == ﾒEDITﾓ) BREAK;
** WIN_CLOSE() **
WIN_CLOSE(INT window_id);
The WIN_CLOSE() function closes an open window. The window_id must be a valid value returned by the WIN_OPEN(), WIN_FIND() or WIN_ACTIVE() functions.
Examples:
WIN_CLOSE(win); // close window in ﾒwinﾓ
WIN_CLOSE(WIN_ACTIVE(0)); // close the active window
** WIN_NOTE() **
INT button = WIN_NOTE(INT type, STR text);
The WIN_NOTE() function displays some kind of ﾒnoteﾓ in a window. The type determines which type of icon should be displayed (alert, note, warning) and what button choices are available (OK, Cancel, Yes, No or a combination). The following types are supported:
1 Icon = Stop; Button = OK (default).
2 Icon = Note; Buttons = Cancel, OK (default).
3 Icon = Alert; Buttons = OK, Cancel (default).
4 Icon = Note; Button = OK (default)
5 Icon = Alert; Buttons = Yes (default), No, Cancel.
The result returned by WIN_NOTE() is a number that corresponds to the button that was pressed. The buttons return the following values: OK=1, Cancel=-1, Yes=1, No=0.
Examples:
WIN_NOTE(1, ﾒMacro Failedﾓ);
WIN_NOTE(5, ﾒContinue with macro?ﾓ);
** WIN_WAIT(INT window_id); **
The WIN_WAIT() function waits for a window to close. The WIN_WAIT() function is useful for synchronizing the activity of a macro to user interaction within a window.
Examples:
WIN_WAIT(WIN_FIND(ﾒTestﾓ)); // wait for window called ﾒtestﾓ to close
WIN_WAIT(WIN_ACTIVE(0)); // wait for the active window to close
□*** Dialog Functions ***
The dialog functions allow DIRC to create a complete dialog windows and interact with the user in the same mannor as the application. From the perspective of the user, there is no way to tell the difference between a dialog created by the ﾒapplicationﾓ and by a ﾒmacroﾓ.
Creating dialog windows takes some effort, but can be done without too much difficulty. There are basically four steps involved: First, use the dialog functions to build a dialog template string. The string is a specia "description" of the dialog which DIRC creates the actual dialog from. Second, use the D_OPEN() function to open the dialog. Third, use D_EVENT() to monitor the dialog (i.e., check for button clicks). Fourth, close the window after the you are finished using it (usually after the user presses a button or clicks the close box).
A dialog description is long string which is created by concatenating together dialog element functions (buttons, input fields, static text, dividers, etc) to a window frame (returned by the D_NEW() function). Many of the dialog element functions use a "where" argument which is a string that describes where that particular element should be positioned within the window. Generally, it is useful to position dialog elements relative to prior elements (with the first element in the upper-left corner). DIRC includes simple, but powerful way of expressing the location of each element in text form. The following code sample shows an example dialog description:
The D_NEW() function defines the window frame and style while the other functions (such as D_FORM, D_DIVIDER, D_TEXT, D_RADIO, D_TOGGLE, D_DEFAULT and D_BUTTON) each create individual dialog elements within the window. The first argument to each of these functions is a string which determines where to place the element. The string takes the form of "vert_base+offset horiz_base+offset". The codes ("PB", "WT", "PY", etc.) give the basis from which the new position should be measured. The offset (+0, +5, +10, -0, etc.) give the exact position relative to the base position. The valid positioning codes are:
WT - Align top of item relative to top of window.
WB - Align bottom of item relative to bottom of window.
WL - Align left of item relative to left of window.
WR - Align right of item relative to right of window.
PT - Align top of item relative to bottom of previous item.
PB - Align bottom of item relative to top of previous item.
PY - Align baseline of item relative to baseline of previous item.
PL - Align left of item relative to right of previous item.
PR - Align right of item relative to left of previous item.
PX - Align basepoint of item relative to basepoint of previous item.
AT - Align top of item relative to absolute top of window
AB - Align bottom of item relative to absolute top of window.
AY - Align baseline of item relative to absolute top of window.
AL - Align left of item relative to absolute left of window.
AR - Align right of item relative to absolute left of window.
AX - Align basepoint of item relative to absolute left of window.
Example:
INT win,prog;
STR tmpl,event;
tmpl = D_NEW(0,0,60,300,2+4+256,"Processing")+
D_FORM("WT+0 WL+0",100,-1,"Status:")+
D_PROG("WB-3 WL+0",13,200,"~prog")+
D_BUTTON("WB+0 WR+0","Stop");
win = D_OPEN(tmpl);
prog = 0;
WHILE (prog <= 100) {
event = D_EVENT(win,1,"B");
D_SET(win,"~prog",STR_NUM(prog));
IF (event != "") { BREAK }
prog = prog + 1;
DELAY(5); // do work here
}
D_CLOSE(win);
END;
---
There is one little "gotcha" about this macro. It is important to do the
D_SET() right after the D_EVENT(). This is because doing a D_SET() has the side
effect of signaling a change in the dialog. If you do a D_SET() following by a
D_EVENT(win,1,""), you will get back "~prog" indicating the progress indicator
has changed. In fact, it has. You just changed it with D_SET(). This kind of
feedback may seem strange, but it is necessary since there is no way for the
dialog to actually know who changed what or why. The "event" queue for a dialog
is only 1 item deep so the most recent item remains.
** D_NEW() **
STR tmpl = D_NEW (INT top, INT left, INT len, INT wid, INT type, STR title);
The D_NEW() function returns a description of a dialog window for use with the
D_OPEN() function. Use this function at the start of a dialog template description to specify the location, size, type and title of a window. The window type is determines by adding together special values. The following values are available:
* Window Type Values *
1 = Unused
2 = Allow resizing (no grow box displayed)
4 = Display zoom box
8 = Draw window with drop-shadow
16 = Display title bar (set automatically if title is not null)
32 = Modal dialog window
64 = Rounded corners on window
128 = Display as floating window
256 = Display close box
512 = Allow color (set automatically for non-white background)
STR tmpl = D_FONT(STR fontname, INT fontsize, INT kind);
The D_FONT() function sets the desired font for all items which follow it in a dialog template. The font for "prompts" and "input" can be set separately. This means that an input field can use a different font for the prompt and input. The two "kind" values are 1=prompt, 2=input.
Examples:
tmpl = tmpl + D_FONT("monaco",9,2); // use monaco-9 for next input field
** D_BUTTON() **
STR tmpl = D_BUTTON(STR where, STR title);
The D_BUTTON() function adds a button to a dialog template. The 'where' argument specifies where the button should be displayed. The 'title' is the name of the button.
Examples:
tmpl = tmpl + D_BUTTON("WB-0 WL+0","OK"); // add OK button to lower-left
** D_DEFAULT() **
STR tmpl = D_DEFAULT(STR where, STR title);
The D_DEFAULT() function adds a "default button" to a dialog template. The default button has a highlight drawn around it. When return is pressed, it is the same as clicking the default button. A dialog may contain only a single default button. See D_BUTTON() for more information.
Examples:
tmpl = tmpl + D_DEFAULT("WB-0 WL+0","OK"); // add default OK button to LL
** D_TOGGLE() **
STR tmpl = D_TOGGLE(STR where, STR name);
The D_TOGGLE() function adds a checkbox to a dialog template. The checkbox is initially off unless preceded by a D_PRESET() function.
STR tmpl = D_RADIO(STR where, INT group, STR name);
The D_RADIO() function adds a radio button to a dialog template. The 'group' specifies which radio buttons are associated with each other. When you click on a radio button, all other radio buttons in that same group are turned off.
Examples:
tmpl = tmpl + D_RADIO("PB+0 WL+0",1,"My Radio Button"); // add radio button
** D_INPUT() **
STR tmpl = D_INPUT(STR where, INT maxlen, INT width, INT length, STR prompt);
The D_INPUT() function adds an input field to a dialog template. The 'maxlen' limits the length of the input which can be entered in the field. The 'width' and 'length' control the size of the input rectangle. You can use -1 for either 'length' or 'width' to use an internally calculated default value. The 'prompt' is the text which appears to the left of the input. A 'prompt' which starts with the tilda (~) character is not displayed (but can still be used to reference the field).
STR tmpl = D_IMAGE(STR where, INT type, STR resname);
The D_IMAGE() function is used to display an image in a dialog (either an icon or picture). The 'type' indicates what kind of image should be displayed. It can be 'PICT', 'ICON', 'cicn', 'icn8', 'icn4' or 'icn#'. The 'resname' corresponds to a resource usually located in the PT Images file.
STR tmpl = D_DIVIDER(STR where, INT length, INT width, INT pattern);
The D_DIVIDER() function displays a divider line within a dialog (horizontal, vertical or rectangular). A horizontal or vertical line is created by using a 'length' or 'width' of 1. The 'pattern' indicates whether a dashed or solid divider is drawn (0=dashed, 1=solid).
Examples:
tmpl = tmpl + D_DIVIDER("PB+0 WL+0",300,1,0);
** D_TEXT() **
STR tmpl = D_TEXT(STR where, STR text);
The D_TEXT() function displays static text within a dialog. The text cannot be changed within the dialog. The text can include RETURN characters if the text uses more than a single line.
Examples:
tmpl = tmpl + D_TEXT(STR where, STR text);
** D_FORM() **
STR tmpl = D_FORM(STR where, INT width, INT length, STR prompt);
The D_FORM() function is used to create a dynamic text area which you can change after a dialog is displayed. If the 'prompt' starts with the tilda (~) character, then it is not displayed (but is still used to reference the item). A form is very much like an input item except the user cannot change it and it has no border.
STR tmpl = D_PROG(STR where, INT height, INT width, STR title);
The D_PROG() function is used to add a progress indicator to a dialog template.
Once the indicator is added, use D_SET() to change its value. The 'title' string is required in order to be able to identify the item for D_SET(). If you don't want a title of the item, prefix the title with a tilde (such as ~prog). This gives the item a title you can use with D_SET() without displaying it.
** D_POPUP() **
STR tmpl = D_POPUP(STR where, INT resid, STR prompt);
The D_POPUP() function is used to add a popup menu to a dialog template. The popup menu must already exist (either through the use of a utility such as ResEdit or via the D_MENU() function).
Examples:
tmpl = tmpl + D_POPUP("WT+0 WL+0",768,"Speed:");
** D_MENU() **
INT resid = D_MENU(INT resid, STR desc);
The D_MENU() function allows a popup menu to be created for use with the D_POPUP() function. If the 'resid' argument is zero, then D_MENU() returns a recently unused resid number (this allows dynamic popup menus to be created). The format of the menu itself is the same as used by the Macintosh Toolbox _AddMenuDesc trap;
Examples:
resid = D_MENU(0,"Hello;-;World");
** D_LIST() **
STR tmpl = D_LIST(STR where, INT width, INT length, STR title);
The D_LIST() function allows a list item to be added to a dialog. After the list item is added, the list contents must be set after the dialog is displayed using the D_CONTENT() function.
Examples:
STR tmpl = D_LIST("WT-10 WL-10",100,200,"~list");
** D_GROW() **
The D_GROW() function is used to add a grow box to a dialog. Though some window types may show the grow box even without D_GROW() as part of the dialog description, D_GROW() should be included when a grow box is required.
Examples:
STR tmpl = D_GROW();
** D_PRESET() **
STR tmpl = D_PRESET(VAR value);
The D_PRESET() function is used to assign initial values to dialog items. When a dialog is first created, the items within the dialog usually have "empty" values (input fields are blank, checkboxes are unchecked, etc.) The D_PRESET() function allows initial item values to be specified within the template. A D_PRESET() must be used immediately prior to the item which contains the data to be preset.
NOTE: Not every dialog element type accepts the D_PRESET() function (D_FORM() and D_LIST() do not). As an alternative to D_PRESET(), you can use D_SET() after a dialog is created to set the value of a particular item.
The D_GET() function is used to return the value of a dialog item. The 'win' must be a valid open dialog window. The 'what' is the name of the individual item. D_GET() is used to extract user input from a dialog.
Examples:
PRINTF("%s^m",D_GET(win,"My Name:"));
** D_SET() **
D_SET(INT win, STR what, STR value);
The D_SET() function is used to set the value of a dialog item. The 'win' must be a valid open dialog window. The 'what' is the name of the individual item. The 'value' is the new value for the item. D_SET() is used to set values for items which are not set with D_PRESET().
** D_CONTENT() **
D_CONTENT(INT win, STR item, STR data);
The D_CONTENT() function is used to set the contents a dialog item. This is different from the value of a dialog item. The idea of contents applies to certain types of dialog items such as popup menu and list boxes. Within these items, the contents represents the list of possible choices while the value represents the current choice. At present, D_CONTENT() can only be used with list boxes.
The format of D_CONTENT() data for a list box is an array created using the ARRAY_xxx() functions. The array should be created to the proper length in advance with the proper number of entries (extra entries will display as blank lines).
Examples:
D_CONTENT(win,"~list",index());
** D_MOVE() **
D_MOVE(INT win, INT top, INT btm, INT lft, INT rgt, INT new-top, INT new-lft);
The D_MOVE() function moves all the items within the rectangle defined by 'top', 'btm', 'lft', 'rgt' to a different rectangle starting at 'new-top', 'new-lft'. You can use D_MOVE() to create a multi-page dialog by moving groups of items off the visible dialog area to some "invisible" portion of the dialog (an area beyond the visible edge of the window) in response to the user changing some dialog item in the window.
Examples:
D_MOVE(0,0,100,200,0,400); // move all in 0,0,100,200 rect to 0,400
** D_SIZE() **
INT size = D_SIZE(INT win, STR what, INT width, INT length);
The D_SIZE() function changes the size of an item. The 'what' is the name of the individual item. After D_SIZE(), the dialog item will be redrawn to the new size. To "hide" an item, do not try and size it to 0,0. Instead, use D_MOVE() to move the item off the visible page.
Examples:
** D_OPEN() **
win = D_OPEN(INT win, STR tmpl);
The D_OPEN function takes a dialog description and creates/opens the dialog window. It returns a window identifier for use with other window function. If the dialog cannot be created for some reason, D_OPEN() returns zero.
Examples:
D_OPEN();
** D_EVENT() **
STR item = D_EVENT(INT win, INT timeout, STR filter);
The D_EVENT() function waits for activity within a dialog. The filter argument specifies what kind of events are returned (see the list below). The timeout argument specifies how long D_EVENT() should wait for an event (in 1/100th of a second). The timeout can be disabled by giving it a value of zero. D_EVENT() returns the title of the item causing the event, @GROW if the user resized the window, @CLOSE if the user closed the window, or null (empty string) for a timeout. The filter is a string of characters where each character represents a type of dialog item. The valid filter characters are:
G = Grow box.
B = Button.
I = Input field.
P = Popup menu.
T = Toggle box.
R = Radio button.
L = List box.
Examples:
SWITCH(D_EVENT(win,50,"BGL")) { ... }
** D_CLOSE() **
D_CLOSE(INT win);
The D_CLOSE() function will close an open dialog. This function should only be used to close dialog windows which were created by D_OPEN(). Using it to close dialog windows generated by the application can have unpredictable results.
Examples:
D_CLOSE(win);
□*** Menu Functions ***
The menu functions allow DIRC to create a new menu items and interact with the user in the same mannor as the application. From the perspective of the user, there is no way to tell the difference between a menu/menu-item created by the ﾒapplicationﾓ and by a ﾒmacroﾓ.
** MM_LOOKUP() **
STR item = MM_LOOKUP(STR where, INT index);
The MM_LOOKUP() function is used to determine what items are in a menu. The function requires a base menu reference (the 'where' argument) and an index into the menu (where 0 is the first item). If the index is out of range (beyond the end of the menu), null is returned.
Examples:
PRINT(MM_LOOKUP("File:",1)); // display "Open"
** MM_KEY() **
STR key = MM_KEY(STR menu, STR key);
The MM_KEY() function will get/set the keyboard equivilent for a pulldown menu. This function performs the same operation as UI_EQUIV. In fact, UI_EQUIV() is a library function which calls MM_KEY() to do the work. To remove the keyboard equivilent for a menu item, set 'key' to space (" "). To get the current keyboard equivilent without changing it, set 'key' to null ("").
Examples:
MM_KEY("Edit:Make Index","-");
** MM_MARK() **
STR mark = MM_MARK(STR menu, STR mark);
The MM_MARK() function will get/set the menu marker character for a pulldown menu. To remove an existing menu marker, set 'mark' to space (" "). To get the current marker, set 'mark' to null ("").
Examples:
MM_MARK("PTMM:Inbox",">");
** MM_ICON() **
STR icon = MM_ICON(STR menu, STR icon);
The MM_ICON() function will get/set the menu icon for a pulldown menu. To remove an existing menu icon, set 'icon' to space (" "). To get the current menu icon, set 'icon' to null ("").
** MM_STATE() **
STR state = MM_STATE(STR menu, STR state);
The MM_STATE() function determines how a pulldown menu item is enabled/disabled and made visible/invisible in response to the application state. This function operations by using a special "state code" to tell the menu system how to display menu according to the application state. Because of the complexity of the state code and the difficulty of use, this function should not be used. It is included only for completeness.
** MM_CODE() **
STR code = MM_CODE(STR menu, STR code);
The MM_CODE() function determines the action that is performed by a pulldown menu. This function operates by assigning a CDL script to the menu item. CDL is a special internal command language which controls application operation. Because of the complexity of CDL and the difficulty of use, this function should not be used. It is included only for completeness.
** MM_INSERT() **
STR menu = MM_INSERT(STR where, STR what, INT enable);
The MM_INSERT() function adds a new menu item to the pulldown menus. After the new item is added, it returns a special "menu identifier" string which can be used with other menu functions to get/set attributes of the menu. Since this function requires the use of MM_STATE() and MM_CODE() to be useful, and these functions are not intended for end-user use, this function is of little use for the average user.
** MM_DELETE() **
INT error = MM_DELETE(STR menu);
The MM_DELETE() function will delete the named menu from the menubar. The menu specifier must be a full path including all submenus. A non-zero result indicates an error during the delete (menu not found).
Examples:
MM_DELETE("Connect:Rebuild Menu");
□*** Preference Functions ***
There are three functions which allow many preference values to be queried or set. The preferences control a variety of program options throughout the applications. Each individual preference is designated by a 4 character name which is passed to the function. The following preferences can be changed:
** Preference Names **
XSFG (int) Foreground transfer complete sound (resource id)
XSBG (int) Background transfer complete sound (resource id)
XC32 (int) Use CRC-32 (0 or 1)
XFRC (int) Force protocols according to menu (0 or 1)
XTXT (str) Default text file type (4 char string)
XTXC (str) Default text file creator (4 char string)
XBIN (str) Default binary file type (4 char string)
The PREF_GET() function returns the current value of the specified preference. If the scope is omitted or zero, then the global preference value is returned. If scope corresponds to a session id, then the preference for that session is returned.
Examples:
x = PREF_GET(ﾒEDSPﾓ); // get value of editor space-show pref
y = PREF_GET(ses,ﾒXSFNﾓ); // get filename conversion pref
** PREF_SET() **
PREF_SET([INT scope,] STR pref, VAR data);
The PREF_SET() function sets the value of the specified preference. If the scope is omitted or zero, then the global preference is set. If scope corresponds to a session id, then the preference is set for that session only.
PREF_SET(ses,ﾒZCTLﾓ,1); // make zmodem escape ctrl chars
** PREF_DEL() **
PREF_DEL([INT scope,] STR pref, VAR data);
The PREF_DEL() function deletes the specified preference. Functions which would otherwise use that preference use a default value instead. If the scope is omitted or zero, then the global preference is deleted. If scope corresponds to a session id, then the preference is deleted for that session only.
